<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Using the development tools in applications
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot019.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot018.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc39">4.2</A>&nbsp;&nbsp;Using the development tools in applications</H2><UL>
<LI><A HREF="umsroot020.html#toc21">Using the Development tools in the Tcl/Tk Embedding Interface</A>
<LI><A HREF="umsroot020.html#toc22">Using the Remote Development Tools</A>
</UL>

The user can develop their own ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> applications using the
development tools independent of the TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> toplevel. There are two
ways to do this, depending on if the user is also using the embedding Tcl/Tk
interface (see the Embedding and Interfacing Manual) to provide a graphical
front end:
<UL CLASS="itemize"><LI CLASS="li-itemize">
The user is using the embedding Tcl/Tk interface, and is thus
developing a graphical front end in Tk. In this case the user can use the
 development tools via the embedding interface. This is described in
 section&nbsp;<A HREF="#embedtools">4.2.1</A>. 
<LI CLASS="li-itemize">The user is not using the embedding Tcl/Tk interface. In this case
 the user can use the development tools remotely, by using the remote_tools
 library. This is described in section&nbsp;<A HREF="#useremotetools">4.2.2</A>.
</UL>
<A NAME="toc21"></A>
<H3 CLASS="subsection"><A NAME="htoc40">4.2.1</A>&nbsp;&nbsp;Using the Development tools in the Tcl/Tk Embedding Interface</H3>
<A NAME="embedtools"></A>
The development tool suite was
designed to be independent of the TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> top-level so that they can be
used in a user's application. In effect, the user can replace the
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
top-level with their own alternative top-level. Two simple examples in
which this is done are provided in the <CODE>lib_tcl</CODE> library as
<CODE>example.tcl</CODE> and <CODE>example1.tcl</CODE>. In addition, <CODE>tkeclipse</CODE>
itself, in the file <CODE>tkeclipse.pl</CODE>, can be seen as a more complex
example usage of the interface.<BR>
<BR>
In order to use the Tcl/Tk interface, the system must be initialised as
described in the Embedding manual. In addition, the user's Tcl code should
probably also be provided as a package using Tcl's package facility, in
order to allow the program to run in a different directory. See the
Embedding manual and the example programs for more details on the
initialisation needed. <BR>
<BR>
The user should most likely provide a connection for the output stream
of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> so that output from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> will go somewhere in the GUI. In
addition, especially during the development, it is also useful to connect
the error stream to some window so that errors (such as ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
compilation errors) are seen by the user. This can be done using the
<CODE>ec_queue_connect</CODE> Tcl command described in the embedding manual.<BR>
<BR>
Output from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> need not be sent to a Tk window directly. The Tcl/Tk
code which receives the output can operate on it before displaying it. It
is intended that all such graphical operations should be performed on the
Tcl side, rather than having some primitives provided on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side.<BR>
<BR>
The user can also provide balloon-help to his/her own application. The
balloon help package is part of the Megawidget developed by Jeffrey Hobbs
and used in TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. In order to define a balloon help for a particular
widget, the following Tcl code is needed:
<PRE CLASS="verbatim">
balloonhelp &lt;path&gt; &lt;text&gt;
</PRE>
where <CODE>&lt;path&gt;</CODE> is the pathname of the widget, and <CODE>&lt;text&gt;</CODE> is the
text that the user wants to display in the balloon. <BR>
<BR>
<A NAME="toc22"></A>
<H3 CLASS="subsection"><A NAME="htoc41">4.2.2</A>&nbsp;&nbsp;Using the Remote Development Tools</H3>
<A NAME="useremotetools"></A>
The user can also use the development tools via the remote_tools
library. In this case, the development tools are run as a separate program
from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session, and is attached to it via the Tcl/Tk remote
interface (see the Embedding and Interfacing Manual). This allows any 
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session to use the development tools,
as long as there is the capability for graphical display. <BR>
<BR>
The main purpose for the remote_tools library is to allow the user to 
use the development tools in situations where (s)he cannot use the Tcl/Tk
embedding interface, e.g. if ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is already embedded into another
programming language, or if the user needs to use the tty interface for
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. 
<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center"><DIV CLASS="center">

<IMG SRC="umsroot004.gif"> <IMG SRC="umsroot005.gif">

</DIV></DIV>
<BR>
<BR>
<DIV CLASS="center">Figure 4.3: Remote Development Tools Toplevel (left: ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> active; right:
remote tools active)</DIV><BR>
<BR>

<A NAME="remotetools"></A>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
Once attached to an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session, the remote development tools has
its own window as shown in Figure&nbsp;<A HREF="#remotetools">4.3</A>. The Tools menu is the
same as in TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, providing access to the same suite of development
tools. The main body of the window consists of one button and a status
indicator. The indicator shows wheather the tools can be used or not (the
tools cannot be used when the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is active), and the button
is used to pass control explicitly to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.<BR>
<BR>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session and the development tools are two separate processes
(and in fact they can be running on different machines) that are connected
to each other via the remote Tcl/Tk interface. The interactions of the two
processes are synchronised in that there is a thread-like flow of control
between them: only one process can be `active' at any time. The interaction
is similar to the standard interaction between a debugger and the program
being debugged &ndash; debugging commands can only be issued
while the execution of the program is suspended. In the same way, the user
can only interact with the remote tools window when execution in the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session is suspended. The toplevel window of the remote tools
has an indicator showing which side has control (see Figure&nbsp;<A HREF="#remotetools">4.3</A>).
To allow ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to resume execution, control is transferred back from
the remote tools to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. This can either be
done automatically from the tools (e.g. when one of the debug buttons is
pressed in the tracer tool), or control can be transferred explicitly back
to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> via the &#8220;Resume ECLiPSe&#8221; button on the remote tools window.<BR>
<BR>

<H4 CLASS="subsubsection">Starting Remote Tools</H4>
To use the remote tools, the user must first load the remote_tools library
with <CODE>lib(remote_tools)</CODE>. After loading the library, the user can
start the remote tools by
starting the development tools as a separate program and then manually
attach the program to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session. This allows the development
tools to be run on a different machine from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session. In this
case, the user initiates the attachment in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> with
<A HREF="../bips/lib/remote_tools/attach_tools-0.html"><B>attach_tools/0</B></A><A NAME="@default139"></A>:
<PRE CLASS="verbatim">
[eclipse 2]: attach_tools.
Socket created at address holborn.icparc.ic.ac.uk/22849

</PRE>
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> prints the host and port address it expects the remote tools to
attach to, and execution is now suspended waiting for the remote tools to
attach. This is done by running the <B>tktools</B> program, which is located
with the other ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> executables. As stated, this program can be run
on a different machine from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session, as long as the two are
connected via a network such as the internet. A connection window is then
displayed as shown:<BR>
<BR>
<DIV CLASS="center">
<IMG SRC="umsroot006.gif">
</DIV><BR>
<BR>
The same `host' and `port' fields as printed by the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session should 
be entered. The default `host' field is `localhost'. This will work if the
remote tools are ran on the same machine as the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
session. Otherwise the full name of the `host' as given by <B>attach_tools/0</B> needs to be entered:<BR>
<BR>
<DIV CLASS="center">
<IMG SRC="umsroot007.gif">
</DIV><BR>
<BR>
Typing return in the `port' field will start the attachment, and with
success, the remote tools window (see Figure&nbsp;<A HREF="#remotetools">4.3</A>) will be
displayed. The <B>attach_tools/0</B> predicate will also return.<BR>
<BR>
The user is not able to immediately interact directly with the remote
tools, as the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session is initially given control. The user can
use the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session as normal, with the additional availability of
the development tools. For example, the display matrix predicates can be
used as in TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. Also, the tracer tool replaces the previous
tracing facilities of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session (this would typically be the
command-line debugger).<BR>
<BR>
The tools can be triggered by events in the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session as described
above. In order to use the tools in a more interactive way, control should
be handed over to the remote tools. This can be done by calling the
<A HREF="../bips/lib/remote_tools/tools-0.html"><B>tools/0</B></A><A NAME="@default140"></A> predicate. When the remote tools have control, the user can
now interactively select development tools from the Tools menu.<BR>
<BR>
The remote_tools library provides several predicates to facilitate the use
of the remote development tools:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default141"></A><B>tools</B><DD CLASS="dd-description"> Explicitly hands over control to the remote development
tools. The tools window can then be used interactively. Execution on the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session is suspended until the remote tools allows ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to
resume, at which point the predicate succeeds. The predicate will abort if
the development tools is disconnected from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default142"></A><B>attached(?ControlStream)</B><DD CLASS="dd-description"> 
	Checks if the remote development tools have been attached to this 
 ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session or not. If attached, the predicate succeeds and 
 unifies <I>ControlStream</I> with the stream name of the control
 stream. If not attached, th predicate fails.</DL>
Once attached, the remote development tools should be connected until the
user quits the session. Although it is possible to disconnect the tools
from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session (from the File menu in the development tools
window). This is not recommended, as there would not be any debugging
facilities available after the disconnection &ndash; the original tracer would
not be restored. <BR>
<BR>
It is possible to attach the remote development tools to any ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
session, including one that is using the embedding Tcl/Tk interface (and
indeed, to TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> itself). However, using the tools via the embedding
interface is usually the better option if available, because the tools are
more tightly coupled to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> in this case. This means that the
communications between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and the tools are more efficient (and
hence something like the display matrix would perform more efficiently).<BR>
<BR>
<HR>
<A HREF="umsroot019.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot018.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
